Adds a design-time-bounded enum + wire-value table so every SDK-forced
cache refresh can be attributed to a specific cause via the generic
`x-ms-cosmos-refresh-reason` HTTP header. This is the foundation for
tagging address-cache refreshes (and, in future PRs, PK-range-cache,
collection-routing-map, etc.).

Phase 1 scope:
  * `RefreshReason` internal enum with 23 explicitly-numbered members
    (Groups A-D covering server 410, Gone+substatus, transport-synthesized
    Gone, and non-Gone forced refreshes).
  * `RefreshReasonExtensions`:
      - `WireValues` dictionary (single source of truth for enum -> wire
        string; values flat, <=2 dot-segments).
      - `ToHeaderValue` for serialization.
      - `FromTransportErrorCode` exhaustive switch mapping every
        `TransportErrorCode` to a specific reason; default -> `GoneUnknown`.
  * Header constant `HttpConstants.HttpHeaders.CosmosRefreshReason` in
    `src/direct/` (pending upstream `Microsoft.Azure.Cosmos.Direct`
    parallel PR).
  * Carrier field `DocumentServiceRequestContext.RefreshReason` (default
    `Unspecified`) copied by `Clone()`.
  * 12 unit tests validating enum/wire-value coverage, uniqueness, regex
    conformance, and exhaustive transport-code mapping.

No egress wiring or call-site tagging yet - those land in Phase 2/3.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Tag every call site that flips ForceRefreshAddressCache = true (or
equivalent background refresh) with the originating RefreshReason so
the outgoing /addresses request carries x-ms-cosmos-refresh-reason.

Sites tagged:
- GatewayAddressCache suboptimal-server-partition timer -> InsufficientReplicasSuboptimalTimer
- GatewayAddressCache unhealthy-URI background refresh -> ReplicaHealthUnhealthyLongLived (via explicitReason)
- GatewayAddressCache master-suboptimal trigger -> InsufficientReplicasSuboptimalTimer
- ConsistencyWriter barrier request -> InsufficientReplicasQuorum
- QuorumReader barrier request -> InsufficientReplicasQuorum
- StoreReader Gone-retry paths (2) -> classified via new ClassifyPriorGone
  helper walking prior StoreResult exception chain (TransportException.ErrorCode
  for transport-synth 410, else substatus mapping, else GoneServer/GoneUnknown)

New helper:
- RefreshReasonExtensions.ClassifyGoneFromException: centralized exception+substatus
  -> RefreshReason mapping

Tagging preserves upstream-set reasons by only writing when still Unspecified.
Build green (0 warn / 0 err); 12 unit tests still pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Full plan document (problem statement, design choices, 23-value enum
reference with groupings, file inventory covering this repo and upstream
Direct, test surface, phase status, risks) so the PR carries the design
context inline.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Factor FromTransportErrorCode into an internal TryMapKnownTransportErrorCode
  helper that returns false for unhandled codes. The public API still falls
  back to GoneUnknown for unknown codes (graceful in production), but the
  exhaustive unit test now uses TryMap directly, so any new upstream
  TransportErrorCode will fail CI instead of silently folding to GoneUnknown.

- Promote GatewayAddressCache.EmitRefreshReasonHeader from private to internal
  so the validator/precedence behavior can be unit-tested without a full
  gateway round-trip.

- Add 7 ClassifyGoneFromException tests covering every SubStatusCodes branch
  (CompletingSplit, CompletingPartitionMigration, NameCacheIsStale,
  PartitionKeyRangeGone) and the default GoneServer fallback.

- Add RefreshReasonEmissionTests with 6 tests for precedence (explicit > ctx),
  null-request path (on-demand unhealthy-URI refresh), default no-op when
  untagged, and the opt-in ValidateRefreshReasonPresence invariant that
  guards future force-refresh call sites from shipping untagged.

Tests: 25/25 Routing/RefreshReason pass; 22/22 GatewayAddressCache pass.
Build: clean (0 warn / 0 err).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>